1.Обзор системы | 2. Мой первый проект | 3. Модель | 4. Формы @View | 5. Списки @Tab | 6. Объектно-реляционное связывание | 7. Контроллеры | 8. Приложение | 9. Расширенные возможности

Глава 9: Расширенные возможности

Пользовательский интерфейс, генерируемый OpenXava, имеет широчайшие возможности по настройке без необходимости разработки программного кода, полностью готов к использованию и применим в большинстве случаев. Если все же стандартное поведение OpenXava не полностью удовлетворяет ваши нужды, вы можете переопределить поведение системы, разработав свои собственные компоненты интерфейса или переопределив поведение стандартных компонент. Как это сделать, рассказано в этой главе.
Например, при необходимости вы можете определять ваши собственные редакторы, используемые для редактирования/отображения свойств, и даже полностью самостоятельно строить пользовательский интерфейс (используя пользовательские представления JSP).

Редакторы

Создание собственного редактора для одного значения (Single value editors)

Как вы, наверное, уже заметили, при определении представления мы задаем свойства, которые будут отображены, и порядок их отображения, но не описываем, как отображать эти свойства. За это в OpenXava отвечают редакторы.
Итак, редактор описывает, как отображать свойство. Спецификация редактора представляет собой XML описание, совмещенное с фрагментом JSP.
Для переопределения поведения редакторов OpenXava или для того, чтобы добавить свой собственный редактор, вам необходимо внести изменения в файл xava/editors.xml. Если такого файла нет, создайте его.
Формат файла editors.xml:

 <?xml version = "1.0" encoding = "ISO-8859-1"?>
 
 <!DOCTYPE editors SYSTEM "dtds/editors.dtd">
 
 <editors>
 <editor .../> ...
 </editors>

Здесь ничего сложного. Файл просто содержит определение списка редакторов.
Рассмотрим описание редактора более подробно:

 <editor
 url="url" <!-- 1 -->
 format="true|false" <!-- 2 -->
 depends-stereotypes="stereotypes" <!-- 3 -->
 depends-properties="properties" <!-- 4 -->
 frame="true|false" <!-- 5 -->
 >
 <property ... /> ... <!-- 6 -->
 <formatter ... /> <!-- 7 -->
 <for-stereotype ... /> ... <!-- 8 -->
 <for-type ... /> ... <!-- 8 -->
 <for-model-property ... /> ... <!-- 8 -->
 </editor>

1. url (обязательно): URL фрагмента JSP, в котором реализован редактор. Файл с фрагментом должен находится в папке xava/editors (внутри папке web вашего приложения).
2. format (необязательно): Если аттрибут установлен в значение true, то OpenXava выполняет форматирование данных при передаче из HTML и Java и в обратнои направлении. Если значение аттрибута false, то за преобразование данных отвечает используемый редактор (обычно выполняется извлечением данных из request и привязки их к org.openxava.view.View, также в обратном направлении). Значение по-умолчанию true.
3. depends-stereotypes (необязательно): Список стереотипов (stereotypes) через запятую, для которых используется данный редактор.
4. depends-properties (необязательно): Список свойств (properties, разделенных запятой), от которых редактор зависим.
5. frame (необязательно): Если имеет значение true, редактор будет отображен в рамке. Значение по-умолчанию false. TIP: Многострочный редактор в рамке выглядит более привлекательно.
6. property (несколько вхождений, необязательный аттрибут): Установка свойств для передачи в редактор. Используется обычно для создания многоцелевых редакторов, которые могут встречаться несколько раз в пределах одного UI.
7. formatter (одно вхождение, необязательно): класс Java, определяющий преобразование из Java в HTML и наоборот из HTML в Java.
8. for-stereotype или for-type, или for-model-property (обязателен один из указанных параметров, параметры не соместимы): Ассоциирует данный редактор со стереотипом, типом или конкретным свойством модели. Порядок применения параметров: сначала свойство модели, потом стереотип и в конце тип.

Давайте посмотрим на примере определение редактора. Представлен один из редакторов, поставляемых с OpenXava, тем не менее, это хороший учебный пример для начала разработки своего редактора:

 <editor url="textEditor.jsp">
 <for-type type="java.lang.String"/>
 <for-type type="java.math.BigDecimal"/>
 <for-type type="int"/>
 <for-type type="java.lang.Integer"/>
 <for-type type="long"/>
 <for-type type="java.lang.Long"/>
 </editor>

Из примера видно, что к данному редактору привязана целая группа базовых типов, для которых будет использоваться данный редактор. JSP код редактора находится в файле textEditor.jsp (он размещен в папке web/xava/editors вашего проекта OX).
Давайте посмотрим на код textEditor.jsp:

 <%@ page import="org.openxava.model.meta.MetaProperty" %>
 
 <%
 String propertyKey = request.getParameter("propertyKey"); // 1
 MetaProperty p = (MetaProperty) request.getAttribute(propertyKey); // 2
 String fvalue = (String) request.getAttribute(propertyKey + ".fvalue"); // 3
 String align = p.isNumber()?"right":"left"; // 4
 boolean editable="true".equals(request.getParameter("editable")); // 5
 String disabled=editable?"":"disabled"; // 5
 String script = request.getParameter("script"); // 6
 boolean label = org.openxava.util.XavaPreferences.getInstance().isReadOnlyAsLabel();
 if (editable || !label) { // 5
 %>
 <input id="<%=propertyKey%>" name="<%=propertyKey%>" class=editor <!-- 1 -->
 type="text"
 title="<%=p.getDescription(request)%>"
 align='<%=align%>' <!-- 4 -->
 maxlength="<%=p.getSize()%>"
 size="<%=p.getSize()%>"
 value="<%=fvalue%>" <!-- 3 -->
 <%=disabled%> <!-- 5 -->
 <%=script%> <!-- 6 -->
 />
 <%
 } else {
 %>
 <%=fvalue%>&nbsp;
 <%
 }
 %>
 <% if (!editable) { %>
 <input type="hidden" name="<%=propertyKey%>" value="<%=fvalue%>">
 <% } %>

Редактор реализован на JSP. Он обрабатывает параметры HTTP запроса request, а также использует аттибуты запроса, специфичным для OpenXava способом (описано далее).
Первове, что он делает - он получает HTML id, используя метод propertyKey (1). Получив id, мы может обратиться к объекту MetaProperty (2) (который содержит мета-информацию свойства, которая необходима для корректного редактирования значения свойсвта). Аттрибут fvalue (3) содержит значение редактируемого свойства, отформатированное и готовое к отображению в пользовательском интерфейсе. Аттрибуты Align (4) (выравнивание) и editable (5) (возможность редактировать) также извлекаются из запроса. Также редактору необходимо извлечь фрагмент JavaScript (6), который нужен для HTML-реализации редактора.
Несмотря на то, что создание редактора на JSP - задача довольно простая, многие вещи, которые, казалось бы, можно сделать только через создание своего редактора, проще и правильно делать изменением конфигурации OX. Приведём пример, попробуйте в файл xava/editors.xml добавить следующее:

 <editor url="textEditor.jsp">
 <formatter class="org.openxava.formatters.UpperCaseFormatter"/>
 <for-type type="java.lang.String"/>
 </editor>

Таким способом, мы можем переопределить поведение OpenXava для свойств, имеющих тип String type. Теперь все свойства типа String будут отображаться и вводиться только в верхнем регистре.
Давайте посмотрим на код класса UpperCaseFormatter:

 package org.openxava.formatters;
 
 import javax.servlet.http.*;
 
 /**
 * @author Javier Paniza
 */
 
 public class UpperCaseFormatter implements IFormatter { // 1
 
 public String format(HttpServletRequest request, Object string) { // 2
 return string==null?"":string.toString().toUpperCase();
 }
 
 public Object parse(HttpServletRequest request, String string) { // 3
 return string==null?"":string.toString().toUpperCase();
 }
 
 }

Первое, на что нужно обратить внимание, это то, что класс-форматтер должен реализовывать интерфейс IFormatter (1). Что в свою очередь приводит к необходимости реализовать методв format() (2), который предназначен для преобразования (форматирования) значения свойства (которое обычно является объектом Java) в строку, которая должна корректно отображаться в HTML. А также необходимо реализовать метод parse() (3), который выполняет обратное преобразование - строка, полученная как результат выполнения формы HTML, должна быть преобразована в значение, которое возможно присвоить свойству.

Создание редактора для множественных значений (Multiple values editors)

Определение редактора многожественных значений происходит примерно также, как определение редактора одного значения, которое мы обсуждали в предыдущем разделе.
Предположим, что вы хотите определить новый стереотип REGIONS, который позволяет пользователю выбрать более одного региона для одного свойства. Использовать стереотип очень просто:

 @Stereotype("REGIONS")
 private String [] regions;
 

Затем вам необходимо добавить новую строку в файл stereotype-type-default.xml:

 <for stereotype="REGIONS" type="String []"/>

А также определить новый редактор в файле editors.xml:

 <editor url="regionsEditor.jsp"> <!-- 1 -->
 <property name="regionsCount" value="3"/> <!-- 2 -->
 <formatter class="org.openxava.formatters.MultipleValuesByPassFormatter"/> <!-- 3 -->
 <for-stereotype stereotype="REGIONS"/>
 </editor>

Объясним подробнее определение нового редактора:

• regionsEditor.jsp (1) - это файл JSP, отвечающий за отрисовку редактора. Вы можете определить свойства, которые будут отсылаться в JSP как параметры запроса (request parameters (2)).
• Класс форматера должен реализовывать интерфейс IMultipleValuesFormatter, который аналогичен IFormatter, но в отличии от исходного использует массив строк String [] вместо одной строки String. В нашем примере мы реализуем простейший форматер, который ничего полезного не делает.

И наконец, нужно написать свой JSP-редактор:

 <%@ page import="java.util.Collection" %>
 <%@ page import="java.util.Collections" %>
 <%@ page import="java.util.Arrays" %>
 <%@ page import="org.openxava.util.Labels" %>
 
 <jsp:useBean id="style" class="org.openxava.web.style.Style" scope="request"/>
 
 <%
 String propertyKey = request.getParameter("propertyKey");
 String [] fvalues = (String []) request.getAttribute(propertyKey + ".fvalue"); // 1
 boolean editable="true".equals(request.getParameter("editable"));
 String disabled=editable?"":"disabled";
 String script = request.getParameter("script");
 boolean label = org.openxava.util.XavaPreferences.getInstance().isReadOnlyAsLabel();
 if (editable || !label) {
 String sregionsCount = request.getParameter("regionsCount");
 int regionsCount = sregionsCount == null?5:Integer.parseInt(sregionsCount);
 Collection regions = fvalues==null?Collections.EMPTY_LIST:Arrays.asList(fvalues);
 %>
 <select id="<%=propertyKey%>" name="<%=propertyKey%>" multiple="multiple"
 class=<%=style.getEditor()%>
 <%=disabled%>
 <%=script%>>
 <%
 for (int i=1; i<regionsCount+1; i++) {
 String selected = regions.contains(Integer.toString(i))?"selected":"";
 %>
 <option
 value="<%=i%>" <%=selected%>>
 <%=Labels.get("regions." + i, request.getLocale())%>
 </option>
 <%
 }
 %>
 </select>
 <%
 }
 else {
 for (int i=0; i<fvalues.length; i++) {
 %>
 <%=Labels.get("regions." + fvalues[i], request.getLocale())%>
 <%
 }
 }
 %>
 
 <%
 if (!editable) {
 for (int i=0; i<fvalues.length; i++) {
 %>
 <input type="hidden" name="<%=propertyKey%>" value="<%=fvalues[i]%>">
 <%
 }
 }
 %>

Как вы, наверное, уже заметили, реализация примерно такая же, как и для редактора одного значения (single value editor). Основное отличие в том, что форматируемое значение (1) в данном случае массив строк (String []), а не простая строка (String).

Пользовательские редакторы и стереотипы для отображения комбо-списков

OpenXava позволяет вместо непосредственного редактирования значений свойства создавать комбо-списки значений свойства и позволять выбирать пользователю из них. При этом список значений, отображаемый в combo-списке, загружается из БД.
Давайте посмотрим, как это реализуется.
Для начала нужно определить свойство:

 @Stereotype("FAMILY")
 private int familyNumber;
 
 @Stereotype("SUBFAMILY")
 private int subfamilyNumber;
 

Затем необходимо сконфигурировать редактор(ы) для данных свойств (вернее, их стереотипов) в файле editors.xml:

 <editor url="descriptionsEditor.jsp"> <!-- 10 -->
 <property name="model" value="Family"/> <!-- 1 -->
 <property name="keyProperty" value="number"/> <!-- 2 -->
 <property name="descriptionProperty" value="description"/> <!-- 3 -->
 <property name="orderByKey" value="true"/> <!-- 4 -->
 <property name="readOnlyAsLabel" value="true"/> <!-- 5 -->
 <for-stereotype stereotype="FAMILY"/> <!-- 11 -->
 </editor>
 
 <!-- Возможно специфицировать зависимости от стереотипов или свойств -->
 <editor url="descriptionsEditor.jsp" <!-- 10 -->
 depends-stereotypes="FAMILY"> <!-- 12 -->
 <!--
 <editor url="descriptionsEditor.jsp" depends-properties="familyNumber"> <!-- 13 -->
 -->
 <property name="model" value="Subfamily"/> <!-- 1 -->
 <property name="keyProperty" value="number"/> <!-- 2 -->
 <property name="descriptionProperties" value="number, description"/> <!-- 3 -->
 <property name="condition" value="${familyNumber} = ?"/> <!-- 6 -->
 <property name="parameterValuesStereotypes" value="FAMILY"/> <!-- 7 -->
 <!--
 <property name="parameterValuesProperties" value="familyNumber"/> <!-- 8 -->
 -->
 <property name="descriptionsFormatter" <!-- 9 -->
 value="org.openxava.test.formatters.FamilyDescriptionsFormatter"/>
 <for-stereotype stereotype="SUBFAMILY"/> <!-- 11 -->
 </editor>

Тепер, при отображении свойств familyNumber и subfamilyNumber) OpenXava будет показывать combo-список для каждого из свойств. При этом сначала комбо-список для свойста family (фамилия) будет заполнен всеми уже созданными в БД фамилиями, а комбо-список subfamily будет пустой. Затем, когда пользователь выберет значение для свойства family, то комбо-список свойства subfamily заполниться из БД и пользователь сможет выбрать значение и для данного свойства.
Чтобы выше описанная логика заработала, вам необходимо указать редактор descriptionsEditor.jsp (10) для стереотипов FAMILY и SUBFAMILY (11) и сконфигурировать корректную передачу параметров в редактор.
Некоторые из параметров, которые можно передать в редактор:

1. model: Модель, из которой будут извлекаться данные. Это может быть имя сущности(например, Invoice) или имя модели для встраимаемой коллекции (например, Invoice.InvoiceDetail).
2. keyProperty или keyProperties: Ключевое свойство или список ключевых свойств. Этот элемент используется для получения значения текущего свойства. Данный элемент не обязателен, т.к. обычно для извлечения значения свойства используются ключевые свойства модели, поэтому определение данного элемента не нужно.
3. descriptionProperty или descriptionProperties: Свойство или список свойств для отображения в комбо-списке.
4. orderByKey: If it has to be ordered by the key, by default it is ordered by description. You can also use order with an order clause in SQL style if you need it.
5. readOnlyAsLabel: Если свойство доступно только для чтения, то отображать его как текстовую метку HTML. Значение по-умолчанию false.
6. condition: Условие ограничения отображаемых данных. Has SQL format, but you can use the property names with ${}, even qualified properties are supported. You can put arguments with ?. This last case is when this property depends on other ones and only obtain data when these other properties change.
7. parameterValuesStereotypes: Список стереотип, от которых зависит данное свойство. It's used to fill the condition arguments and has to match with depends-stereotypes attribute (12).
8. parameterValuesProperties: Список свойств, от которых зависят данные свойства. It's used to fill the condition arguments and has to match with depends-properties attribute (13).
9. descriptionsFormatter: Класс-форматтер для описаний (descriptions), отображаемых в комбо-списке. Форматтер должен реализовывать интерфейс IFormatter.

Использую ниже приведённый пример, вы научите ваши стереотипы отображать простое свойство в виде комбо-списка, заполняемого динамическими данными. Тем не менее, в большинстве случаев более удобно использовать ссылки, отображаемые с помощью @DescriptionsList.

Пользовательские представления JSP и библиотека тегов OpenXava (OX taglibs)

OpenXava предоставляет широчайшие возможности по настройке пользовательского интерфейса, об этом рассказано в главе 4. Если имеющие возможности настройки интерфейса не достаточны, то вы можете создать собственные представления, используя JSP. При этом вы можете использовать библиотеки тегов, предоставляемые OpenXava. Давайте рассмотрим выше сказанное на примере выше.

Пример

Сначала, нужно сообщить модулю, что вы хотите использовать собственные страницы JSP. Для этого нужно внести изменения в файл application.xml:

 <module name="SellersJSP" folder="invoicing.variations">
 <model name="Seller"/>
 <view name="ForCustomJSP"/> <!-- 1 -->
 <web-view url="custom-jsp/seller.jsp"/> <!-- 2 -->
 <controller name="Typical"/>
 </module>

Если вы переопределите тег web-view (2) для модуля, OpenXava будет использовать вашу страницу JSP для отображения представления detail вместо того, чтобы создавать представление view автоматически. Optionally you can define an OpenXava view using view (1), this view is used to know the events to throw and the properties to populate, if not it is specified the default view of the entity is used; although it's advisable to create an explicit OpenXava view for your JSP custom view, in this way you can control the events, the properties to populate, the focus order, etc explicitly. You can put your JSP inside web/custom-jsp (or other of your choice) folder of your project, and it can be as this one:

 <%@ include file="../xava/imports.jsp"%>
 
 <table>
 <tr>
 <td>Number: </td>
 <td>
 <xava:editor property="number"/>
 </td>
 </tr>
 <tr>
 <td>Name: </td>
 <td>
 <xava:editor property="name"/>
 </td>
 </tr>
 
 <tr>
 <td>Level: </td>
 <td>
 <xava:editor property="level.id"/>
 <xava:editor property="level.description"/>
 </td>
 </tr>
 </table>

Только ваша фантазия ограчивает функциональность вашей страницы JSP. Тем не менее, мы рекомендуем по возможности использовать стандартные теги OpenXava. В этом случае вам не придется заново изобретать велосипед, интегрируя свой код с OpenXava. Например, тег <xava:editor/> отображает редактор для редактирования / отображения значения свойства. Данный тег в том числе создает скрипт javascript для инициации событий, необходимых для корректной работы OX. При использовании тега <xava:editor/> управление отображаемыми данными осуществляется через объект xava_view (тип org.openxava.view.View ). По-умолчанию используются стандартные контролеры OpenXava (включая CRUD).
Можно использовать квалицированные имена свойств (qualified properties) (например, level.id или level.description) (начиная с версии v2.0.1), более того, OX заменит level.id, level.description на соответствующие реальные значения. Если вы используете теги JSP из библиотеки OpenXava, то все возможности стандартного поведения интерфейса доступны внутри вашей страницы JSP.
Давайте рассмотрим теги из библиотеки OpenXava taglibs.

xava:editor

Тег <xava:editor/> создает редактор для свойства (т.е. HTML control) точно также, как делает OpenXava при автоматической генерации интерфейса.

 <xava:editor
 property="propertyName" <!-- 1 -->
 editable="true|false" <!-- 2 New in v2.0.1 -->
 throwPropertyChanged="true|false" <!-- 3 New in v2.0.1 -->
 />

1. property (обязательный параметр): Свойство модели, ассоциированной с текущим модулем
2. editable (необязательный параметр): Начиная с версии v2.0.1. Наделяет редактор возможностью редактирования. Если параметр не определен, то используется значение по-умолчанию.
3. throwPropertyChanged (необязательный параметр): Начиная с версии v2.0.1. Сообщает редактору о необходимости генерировать события изменения свойства (throws property changed event). Если параметр не определен, то используется значение по-умолчанию.

Данный тег создает скрипт JavaScript точно такой же, как используется в представлении, созданном автоматически. Поддерживается использование квалифицированных свойств (qualified properties (properties of references)) (начиная с версии v2.0.1).

Теги xava:action, xava:link, xava:image, xava:button

Тег <xava:action/> позволяет отобразить "действие", т.е. кнопку или изображение, при нажатии которого выполняется действие OX.

 <xava:action action="controller.action" argv="argv"/>

Аттрибуты тега action указывают действие, которое нужно выполнить (параметр action), и параметры для передачи данному действию (параметр argv , необязателен). Пример:

 <xava:action action="CRUD.save" argv="resetAfter=true"/>

В данном примере, если пользователь кликнет по данному "действию", то будет выполнено действие CRUD.save, перед этим будет выставлено свойство resetAfter property данного действия.
Действие отображается как изображение, если с ним ассоциировано изображение. В противном случае, оно отображается как кнопка.Если вы хотите жестко определить стиль отображения, то вам необходимо вместо <xava:action/> использовать теги с предопределенным стилем <xava:button/> (кнопка), <xava:image/> (изображние) или <xava:link/> (ссылка).
Действие может иметь пустое значение (начиная с версии v2.2.1). Пример:

 <xava:action action=""/>

В этом примере данный тег не выполняет никаких действий и не генерирует ошибок. Такой вариант использования тега , если вы формируете имя действия автоматически (например, так action=”<%=mycode()%>”) и значение имени действия в некоторых случаях может быть незаполнено.

Тег xava:message (начиная с версии v2.0.3)

Тег <xava:message/> позволяет отобразить в HTML сообщение из ресусных файлов i18n OpenXava.

 <xava:message key="message_key" param="messageParam" intParam="messageParam"/>

Сначала OX ищет сообщение в файлах конкретного проекта (YourProject/i18n/YourProject-messages.properties). Если такой идентификатор сообщения message_key там не определен, то поиск продолжается в стандартных файлах OpenXava (OpenXava/i18n/Messages.properties).
Аттрибуты param и intParam являются необязательными. Параметр intParam используется, если для корректного отображения сообщения необходимо передать параметр типа int. Если вы используете Java 5, то можете всегда использовать нетипизированный аттрибут param, параметр будет приведен к нужному типу автоматически (autoboxing) .
Данные тег отображает сообщение как простой текст и не поддерживает форматирование тегами HTML.
Пример:

 <xava:message key="list_count" intParam="<%=totalSize%>"/>

Тег xava:descriptionsList (начиная с версии v2.0.3)

Тег <xava:descriptionsList/> позволяет вам отрисовать комбо-список HTML для свойства-ссылки таким же образом, как это делает OpenXava, когда создает пользовательский интерфейс автоматически.

 <xava:descriptionsList
 reference="referenceName" <!-- 1 -->
 />

Параметры:

1. reference (обязательный параметр): Ссылка на модель, ассоциированную с текущем модулем.

Данный тег добавляет JavaScript, что позволяет представлению работать точно также, как если бы пользовательский интерфейс был сгенерирован автоматически.
Пример:

 <tr>
 <td>Level: </td>
 <td>
 <xava:descriptionsList reference="level"/>
 </td>
 </tr>

В данном примере level (уровень) - это свойство-ссылка текущей модели(например, Seller). Комбо-список будет отображать список всех доступных уровней.